下载APP
关闭
渠道合作
推荐作者
26｜文档：如何给你的组件库设计一个可交互式文档？
2021-12-20 大圣
《玩转Vue 3全家桶》
你好，我是大圣。
在我们实现了组件库核心的组件内容之后，我们就需要提供一个可交互的组件文档给用户使用和学习了。这个文档页面主要包含组件的描述，组件 Demo 示例的展示、描述和代码，并且每个组件都应该有详细的参数文档。
现在，我们从上述文档页包含的信息来梳理一下我们的需求。我们需要用最简洁的语法来写页面，还需要用最简洁的语法来展示 Demo + 源代码 + 示例描述。那么从语法上来说，首选就是 Markdown 无疑了，因为它既简洁又强大。
那在我们正式开始设计文档之前，我们还需要对齐一下。如果要展示 Demo 和源码的话，为了能更高效且低成本的维护，我们会把一个示例的 Demo + 源码 + 示例描述放到一个文件里，尽量多的去复用，这样可以减少需要维护的代码。而做示例展示的话，本质上可以说是跟 Markdown 的转译一致，都是 Markdown -> HTML，只是转译的规则我们需要拓展一下。接下来我们就正式开始了。
VuePress
首先我们需要一个能基于 Markdown 构建文档的工具，我推荐 VuePress。它是 Vue 官网团队维护的在线技术文档工具，样式和 Vue 的官方文档保持一致。
VuePress 内置了 Markdown 的扩展，写文档的时候就是用 Markdown 语法进行渲染的。最让人省心的是，它可以直接在 Markdown 里面使用 Vue 组件，这就意味着我们可以直接在 Markdown 中写上一个个的组件库的使用代码，就可以直接展示运行效果了。
我们可以在项目中执行下面的代码安装 VuePress 的最新版本：
然后我们新建 docs 目录作为文档目录，新建 docs/README.md 文件作为文档的首页。除了 Markdown 之外，我们可以直接使用 VuePress 的语法扩展对组件进行渲染。
我们在 README.md 中输入上面的内容，通过 title 配置网站的标题、actions 配置快捷链接、features 配置详情介绍，这样我们就拥有了下面的首页样式：
然后我们进入 docs/.vuepress/ 目录下，新建文件 config.js，这是这个网站的配置页面。下面的代码我们配置了 logo 和导航 navbar，页面顶部右侧就会有首页和安装两个导航。
然后我们创建 docs/install.md 文件，点击顶部导航之后，就会显示 install.md 的信息。我们在文稿中就可以直接写上介绍 Element3 如何安装的文档了，下面的文稿就是 Element3 的安装使用说明。
然后我们在浏览器里点击安装后，就会看到下图的页面显示。Markdown 已经成功渲染为在线文档了，并且代码也自带了高亮显示。
然后我们需要在这个文档系统中支持 Element3，首先执行下面的代码安装 Element3：
然后在项目根目录下的 docs/.vuepress 文件夹中新建文件 clientAppEnhance.js，这是 VuerPress 的客户端扩展文件。我们导入了 defineClientAppEnhance 来返回客户端的扩展配置。这个函数中会传递 Vue 的实例 App 以及路由配置 Router，我们使用 app.use 来全局注册 Element3 组件，就可以直接在 Markdown 中使用 Element3 的组件了。
这样 VuePress 就内置了 Element3。我们在 docs 下面新建 button.md 文件，可以直接在 Markdown 中使用 Element3 的组件进行演示。下面的文稿中我们直接使用了 el-button 组件演示效果。
然后进入 docs/.vuepress/config.js 中，新增侧边栏 sidebar 的配置之后，就可以看到下图的效果了。
这样我们就基于 VuePress 支持了 Element3 组件库的文档功能，剩下的就是给每个组件写好文档即可。
但是这样的话，el-button 的源码就写了两次，如果我们想更好地定制组件库文档，就需要自己解析 Markdown 文件，在内部支持 Vue 组件的效果显示和源码展示，也就相当于定制了一个自己的 VuePress。
它能直接使用下面的:::demo 语法，在标记内部代码的同时，显示渲染效果和源码，也就是下图 Element3 官网的渲染效果。
那么接下来我们就看看如何定制，具体操作一下。
解析 Markdown
我们需要自己实现一个 Markdown-loader，对 Markdown 语法进行扩展。
Element3 中使用 Markdown-it 进行 Markdown 语法的解析和扩展。Markdown-it 导出一个函数，这个函数可以把 Markdown 语法解析为 HTML 标签。这里我们需要做的就是解析出 Markdown 中的 demo 语法，渲染其中的 Vue 组件，并且同时能把源码也显示在组件下方，这样就完成了扩展任务。
下面的代码就是全部解析的逻辑：首先我们使用 md.render 把 Markdown 渲染成为 HTML，并且获取内部 demo 子组件；在获取了 demo 组件内部的代码之后，调用 genInlineComponentText，把组件通过 Vue 的 compiler 解析成待执行的代码，这一步就是模拟了 Vue 组件解析的过程；然后使用 script 标签包裹编译之后的 Vue 组件；最后再把组件的源码放在后面，demo 组件的解析就完成了。
然后我们还要把渲染出来的 Vue 组件整体封装成为 demo-block 组件。在下面的代码中，我们使用扩展 Markdown 的 render 函数，内部使用 demo-block 组件，把 Markdown 渲染的结果渲染在浏览器上。
然后我们就实现了 demo-block 组件。接下来我们新建 DemoBlock.vue，在下面的代码中我们通过 slot 实现了组件的渲染结果和源码高亮的效果，至此我们就成功了实现了 Markdown 中源码演示的效果。
总结
我们来总结一下今天学到的内容。
首先我们使用 Vue 官网文档的构建工具 VuePress 来搭建组件库文档，VuePress 提供了很好的上手体验，Markdown 中可以直接注册使用 Vue 组件，我们在.vuepress 中可以扩展对 Element3 的支持。
如果我们定制需求更多一些，就需要自己解析 Markdown 并且实现对 Vue 组件的支持了，我们可以使用 Markdown-it 插件解析，支持 Vue 组件和代码高亮，这也是现在 Element3 文档的渲染方式。
思考题
最后留给你一道思考题：现在很多组件库开始尝试使用 Storybook 来搭建组件库的文档，那么这个 Storybook 相比于我们实现的文档有什么特色呢？
欢迎你在评论区分享你的看法，也欢迎你把这节课的内容分享给你的同事和朋友们，我们下一讲再见！
上一篇
25｜表格：如何设计一个表格组件
下一篇
27｜自定义渲染器：如何实现Vue的跨端渲染 ？
